<!--
  ~ Copyright (C) 2010 Brockmann Consult GmbH (info@brockmann-consult.de)
  ~
  ~ This program is free software; you can redistribute it and/or modify it
  ~ under the terms of the GNU General Public License as published by the Free
  ~ Software Foundation; either version 3 of the License, or (at your option)
  ~ any later version.
  ~ This program is distributed in the hope that it will be useful, but WITHOUT
  ~ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  ~ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  ~ more details.
  ~
  ~ You should have received a copy of the GNU General Public License along
  ~ with this program; if not, see http://www.gnu.org/licenses/
  -->

<html>
<head>
    <title>Level 3 Binning Operator</title>
    <link rel="stylesheet" href="../style.css">
</head>

<body>
<table class="header">
    <tr class="header">
        <td class="header">&nbsp;
            Level 3 Binning Operator
        </td>
        <td class="header" align="right"><a href="nbdocs://org.esa.snap.snap.help/org/esa/snap/snap/help/docs/general/overview/SnapOverview.html"><img
                src="../images/snap_header.jpg"
                border=0></a>
        </td>
    </tr>
</table>

<h3>The user interface</h3>

<h4>I/O Parameters</h4>

<p>
    Using the I/O Parameters tab, the input products can be set, as well as the target product's name and target
    directory.
    See the screenshot below.
</p>

<p>
    <img src="images/ui-io-parameters.png">
</p>

The <b>Plus</b>-button allows to add products to the binning process.
<ul>
    <li><b><i>Add product(s)</i></b> - Allows to add already opened products</li>
    <li><b><i>Add product file(s)</i></b> - Allows to add specific files from the file system</li>
    <li><b><i>Add directory(s)</i></b> - Allows to add directory and all products within</li>
    <li><b><i>Add directory recursively</i></b> - Allows to add all products within a directory and the sub-directories</li>
</ul>

<h4>Filter</h4>

<p>
    Two filters can be applied to limit the contents of the target product. See the screenshot below for the user
    interface for the filters.
</p>

<p>
    <img src="images/ui-filters.png">
</p>

<h5>Specify target region</h5>

<p>
    The target region filter can be used to set the bounds of the target product. It is able to operate in four
    different modes:
</p>

<ol>
    <li>
        the bounds of the target product are inferred by the bounds of all inputs products; that is, the smallest
        rectangular bounding box that contains all input products is being used.
    </li>
    <li>
        the whole globe is used as region for the target product
    </li>
    <li>
        the bounds of the target product are given by a user-provided WKT, according to this
        <a href="http://docs.geotools.org/stable/javadocs/org/opengis/referencing/doc-files/WKT.html">specification</a>
    </li>
    <li>
        the region of the target product can be drawn and entered using a dedicated world map component
    </li>
</ol>

<h5>
    Specify temporal filtering
</h5>

<p>
    The method that is used to decide which source pixels are used with respect to their observation time.
<ul>
    <li>NONE: ignore pixel observation time, use all source pixels.
    <li>TIME_RANGE: use all pixels that have been acquired in the given binning period.
    <li>SPATIOTEMPORAL_DATADAY: use a sensor-dependent, spatial "data-day" definition with the goal to minimise the tim
        between the first and last observation contributing to the same bin in the given binning period.<br>
        The decision whether a source pixel contributes to a bin or not, is a function of the pixel's observation
        longitude and time<br>
        Requires the parameter 'minDataHour'.
</ul>

<h4>Configuration</h4>

The third tab allows the user to supply the general binning configuration. See the screenshot below for an example.

<p>
    <img src="images/ui-configuration.png">
</p>

<h5>Aggregator definitions</h5>

<p>
    In the upper table the user can specify which data should be aggregated.<br/> Using the <i>plus</i> button
    aggregation definition can be added. Depending on the selected aggregation method
    (AVG, MIN_MAX, ON_MAX_SET, PERCENTIL, ...) different
    parameters can be specified. Multiple aggregation definition can be added.
    The edit button on the right hand side can be used to change to configuration of an existing aggregation definition.
</p>
<p>
    The <i><b>Intermediate Source Bands</b></i> table has 3 columns: "Name", "Expression" and "Valid-Pixel Expression".
    It allows the user to define intermediate bands which are actually not part of the source products. These bands are defined by arithmetic band
    expressions. After defined here, they are selectable as source band for the aggregators.<br>
    The 3rd column is optional and allows to specify a valid pixel expression. If not given, it will be generated by
    combining the valid pixel expression of all bands referenced in the expression. Setting it to <i>true</i> makes all pixels valid.
</p>

<h5>Valid expression and target height</h5>

<p>
    Using the valid expression, the user can specify which values in the source products shall be considered. Thus, a
    boolean expression has to be set here. In the configuration of the example screenshot, only pixels that are not over
    land are considered.<br>
    The target height of the source product may be set, too; this value has direct influence on the spatial resolution.
</p>

<h5>Supersampling</h5>

<p>
    As long as the area of an input pixel is small compared to the area of a bin,
    a simple binning is sufficient. In this case,
    the geodetic center coordinate of the Level 2 pixel is used
    to find the bin in the Level 3 grid whose area is intersected by this point.
    If the area of the contributing pixel is equal or even larger than the bin area,
    this simple binning will produce composites with insufficient accuracy and
    visual artifacts such as Moir&eacute; effects will dominate the resulting datasets.</p>

<p>
    The following figure illustrates this problem.</p>

<p>
    <img src="images/chessGrid.png">
</p>

<p><i>Level 2 grid (blue) and Level 3 grid (yellow)</i></p>

<p>The blue chessboard grid refers to the input data,
    the yellow one refers to the final Level 3 grid. As the figure clearly shows,
    single Level 2 pixels cannot be uniquely be assigned to single bins.</p>

<p>
    Supersampling parameter can be used to reduce or avoid the Moir&eacute; effect.
    The Moir&eacute; effect usually occurs when the spatial resolution used for the
    binning is similar to or smaller than the input pixel resolution. The supersampling
    subdivides every input pixel to n x n subpixels which all have the same values but
    different and unique geographical coordinates. This way, an input pixel may be
    distributed to more than one adjacent bin cell.
</p>

<hr>
</body>
</html>
